# HP OpenView Service Desk

## version 4.5
Unlimited Custom Fields

December 2005

© Copyright 2005 Hewlett-Packard Development Company, L.P.

## Content:

Last-minute information
Introduction
Managing Custom Fields
New Custom Fields with Non-Latin Text Support
Generate Web API
Known Errors and Limitations

## LAST-MINUTE INFORMATION

There is no last-minute information.

## Introduction

Service Desk now allows user to create additional custom fields when pre-configured custom fields cannot satisfy their requirement. This document describes how to manage custom fields, and what you need to take into account when configuring custom fields.

Included in this document are instructions for

- managing custom fields (viewing, creating, activating, and deactivating)
- migrating from a previous HP OpenView Service Desk version or another Service Desk instance with the same version
- regenerating the Web API library, which is specific to your own Service Desk environment.

The main audience for this document is Service Desk administrators authorized to configure custom fields.

## Managing Custom Fields

### View of Custom Fields

Before Service Pack 18, HP OpenView Service Desk version 4.5 offered a fixed number of custom fields that could be reconfigured for a specific use. With the new custom fields feature, administrators get the ability to add extra fields to an Service Desk item. This way, the use of custom fields is no longer limited by the number of custom fields offered by Service Desk out of the box. To provide a better overview of these custom fields, this feature also introduces a new view of Custom Fields in the Administrator Console (see Figure 1)

Note: View of Custom Fields can be customized by System Administrator temporarily but will be reset after client restarted.

Figure 1

### When and how to add New Custom Field

The administrator should only add a custom field in case there is no unused custom field of the required type available. To see if there are still unused custom fields for an item, open the Administrator Console, and navigate to Data, Custom Fields (see Figure 1). In the right pane, select the item for which you want to add a custom field. Click on the item to open the tree of existing custom fields per type. If the type of field for which you want to use a custom field does not exist under the item, you will need to add a custom field. If there are custom fields of the type that you require under the item, check if there is a field that is not activated. If there is such a field, re-use it. If all fields are activated of the type you need for the item, you will need to add a custom field.

To add a new custom field, click the File -> New menu item, or select the "New custom field" option from the context menu (which you see when you right-click on an item in the view). This opens the New Custom Field dialog box. In principle, there are two main types of custom fields:

- Primitive type custom fields: These are fields that only contain a single piece of data of a pre-defined type. An example of how a primitive type custom field is configured can be seen in Figure 2.
- Entity reference type custom fields: These are lookup fields, meaning that these fields refer to another item in Service Desk. An example of how a entity reference type custom field is configured can be seen in Figure 4.

### Adding a primitive type custom field

As explained in the previous section, a primitive type custom field is used to hold a single piece of data. The most important in configuring this type of field is determining its validation type. The validation type limits what users can enter in a field.

For example, if you introduce a field called "Item has been inspected", it may seem logical to you that you only expect values to indicate that the inspection has happened or has not, in other words: you are only interested to know if the assertion "Item has been inspected" is true or false. A user could interpret the label of the field differently though when entering data. If the "Item has been inspected" field would accept any form of user input, somebody could enter a time and date on which it has happened, or "I will do this next week", or "I don't know". Now, say that in your business process, you want things to happen once the "Item has been inspected" field is set to "Yes". If the values of the field could be anything, it is hard to set up a database rule or UI rule to respond to this appropriately. Also, reporting may become troublesome when a field can contain many different values that are equivalent to "Yes". By giving it a validation type of "Boolean", it is ensured that only values indicating true or false are entered. Of course, there are fields in which you want the user to be able to enter "I don't know" or "Next week". In that case, you would use a validation type "String". If you only want dates to be entered, you could use a validation type "Date".

Related to the validation type is the display format. In the example of the "Item has been inspected" field, there are different ways in which the values true or false could be shown in a form. You could show this as a checkbox, or a radio button that allows the user to switch between Yes and No. The display format allows you to switch between different representations of the same value in the field. If you do not choose a display format, a default display format will be used.

The screenshot below shows an example of a definition of a primitive type custom field.

Figure 2

To define a primitive type custom field, do the following:

1. Make sure you select values for the fields with names in bold in the above screenshot. These fields are mandatory.
2. As "Item", choose the Service Desk item to which you want to add a custom field.
3. As "Field Key", choose a unique name for the custom field. This is the name that Service Desk uses for this field internally, and also the name that you use to access this field in the Web API.
   Please note that after you have added a custom field, you cannot change the item and field key. It is strongly recommended that you decide on a naming convention for custom field keys, to keep the names generic and readable yet meaningful. Do not put the description of what the field is used for in the field key, because this may be unpractical when you want to re-use to field for a different purpose later. The description of what the field is used for goes into the "Name" field. The field key name should describe what the field is instead. This can be seen in Figure 2 for example: the key "Incident_string4k_01" indicates that it is a custom field of the Service Desk item category Incident, with validation type String 4000, and the first of its kind.
4. Select an appropriate value for "Validation type". The next section should help you choose one.
Please note that after you have added a custom field, you cannot change validation type.
5. The remaining fields are optional, and are used the same as in the dialog to edit a custom field.
6. Click OK to add this custom field, or click Cancel to cancel the operation. If the Field Key name is already in use, a dialog box (see Figure 3) informs you that the operation has failed.

Figure 3

### Selecting the right validation type for a new primitive type custom field

The option to create a new primitive type custom field makes it possible to introduce custom fields of types that were not available as custom fields in Service Desk in previous versions. For example, currency and percentage fields were not available as custom fields. As of Service Pack 18, a Service Desk Administrator can introduce these and other new types as new custom fields for an Service Desk item.

The following table lists the available validation types for new custom fields, and what kind of database column is used for their values in the back-end database of Service Desk. Persons that are familiar with the column types of the back-end databases should be able to use those types to determine which validation type to choose. To help the administrator determine the right validation type, the fourth column of the tables provides examples of where this validation types would be used for.

Data Type | Column Type | Example of usage and comments
MS SQL Server | Oracle
Boolean | NUMBER(1) | DECIMAL(1) | Checklists. Was available as custom field before SP18
Currency | NUMBER(10,2) | DECIMAL(10,2) | Cost of an item
Date | DATE | DATETIME | A date without a time. Useful when the time on the date does not matter.
Date Time | DATE | DATETIME | A date plus a time. Was available as custom field before SP18
Duration | FLOAT(32) | FLOAT(32) | Length of a time interval. Was available as custom field before SP18
Entity Reference | NUMBER(18) | DECIMAL(18) | Any lookup field. Please refer to next section for more information.
Number (Double) | FLOAT | DECIMAL | Any number where the part behind the decimal point matters. Its use is preferable over Number (Float).
Number (Float) | FLOAT | DECIMAL | Any number where the part behind the decimal point matters.
Number (Integer) | NUMBER(10) | DECIMAL(10) | Numbers no longer than 10 positions wide. Was available as custom field before SP18
Number (Long) | NUMBER(18) | DECIMAL(18) | Numbers no longer than 18 positions wide.
Percentage | NUMBER(10,2) | DECIMAL(10,2) | Capacity used of an item
String 1 (character) | VARCHAR2(1) | VARCHAR(1) | Drive letters or initials
String 40 (Short Text) | VARCHAR2(40) | VARCHAR(40) | Short text. Was available as custom field before SP18
String 50 (Name) | VARCHAR2(50) | VARCHAR(50) | Name
String 80 (Text) | VARCHAR2(80) | VARCHAR(80) | Text
String 255 (Description) | VARCHAR2(255) | VARCHAR(255) | Description. Was available as custom field before SP18
String 4000 (Long Text) | VARCHAR2(4000) | VARCHAR(4000) | Comments. Was available as custom field before SP18
String 64K (Memo) | LONG | NTEXT | Very long comments. Use this type in moderation, adding this validation type specifically has the most negative impact on performance. Service Desk is not a word processor: there is usually no need to include long texts as fields (attachments will do nicely). Was available as custom field before SP18.
Time | DATE | DATETIME | A time without a date, useful to indicate something that needs to be done on a given time regardless of the day.
Time of Week | FLOAT(32) | FLOAT(32) | A weekday plus a time, useful for weekly recurring events

### Adding an entity reference type custom field

An entity reference type custom field is a lookup field. In other words, it holds a reference to another Service Desk item. Internally in Service Desk, the generic term for an Service Desk item is entity, hence the name "entity reference". In the view of custom fields (as seen in Figure 1), all lookup fields of an Service Desk item are now grouped under the validation type "entity reference".

The screenshot below shows an example of a definition of a new entity reference type field.

Figure 4

Adding an entity reference type custom field is similar to adding a primitive type custom field. The difference is in mainly in the fields that need to be defined for each. To define an entity reference type field, do the following

1. Make sure you select values for the fields with names in bold in the above screenshot. These fields are mandatory.
2. As "Item", choose the Service Desk item to which you want to add a custom field.
3. As "Field Key", choose a unique name for the custom field. The notes about the field key found in the section on "Adding a primitive type custom field" apply here as well.
   An example of a naming convention for field keys for an entity reference type custom field can be seen in Figure 4. In this example, the key "Incident_ref_to_Service_01" indicates that this custom field key is used by a field of the Incident item that refers to the Service Desk Item (a.k.a. entity) Service.
4. As "Validation type", choose Entity Reference. This causes the label of "Entity to" to become bold, indicating that this field is now mandatory.
5. Select the value for "Entity to" using the Quick Find dialog box (see Figure 5). An entity reference type custom field is a lookup field, and this determines what Service Desk item you will see in the lookup field. A custom field of an Service Desk item can only refer to another Service Desk item that is already used in another field. For example, for a Configuration Item, you can select a Person or a Service as value for "entity to". This is because Configuration Item already has lookup fields for those items. You cannot select Service Call or Problem as "entity to", because Configuration Item does not have fields to lookup values of those items.
   Please note that after you have added a custom field, you cannot change validation type and entity to.
   Figure 5
6. The remaining fields are optional, and are used the same as in the dialog to edit a custom field.
7. Click OK to add the custom field, or click Cancel to cancel the operation. If the Field Key name is already in use, a dialog box (see Figure 3) informs you that the operation has failed.

### Activate or Deactivate a Custom Field

Nothing is changed in this operation. To edit an existing custom field, you can double-click it on the view. Alternatively, you can right-click the custom field, then click the Edit menu in the context menu. This opens a dialog box (see Figure 6), from which you can activate or deactivate the custom field, change its name label, change its display format, or restrict its use to a number of categories.

Figure 6

### Custom Fields Migration with ACES

When you add a custom field to an Service Desk item, you effectively change the definition of the Service Desk item itself. This definition, which is called the Object Model, is kept in tables of Service Desk. In addition to maintaining these definitions, Service Desk translates the definitions to save the fields of the Service Desk items to tables and columns in the back end database.

Administrators can use ACES to copy custom field definitions from a staging to a production environment. If the source ACES XML file contains some new custom field definitions that are unknown to the target server, those custom fields can be created during ACES importing. The procedure to export and import custom fields in this way is no different from how it was in previous versions of Service Desk.

When custom field definitions are migrated between two systems using ACES, any newly defined custom field from the source system is transferred as a change to the Object Model of the target Service Desk server. If an error occurs, it is possible that some of the changes made to the Service Desk back-end database cannot be rolled back, leaving it in a corrupted state. It is strongly recommended that you back up the database every time before importing new custom field definitions.

Custom field migration with ACES is backward compatible. XML files exported from a previous version can be successfully imported into the new version.

When importing using ACES, make sure that the option "Overwrite Existing Items" is checked if you want these existing custom fields updated. Note that overriding existing items behaves differently in this version than it did in previous versions. In previous versions, ACES updated the existing custom fields when the option Overwrite Existing Items was not checked. The following table shows how ACES handles the custom field importing in different situations.

Problems/Situations | Solutions/Rules
Custom field already exists in the target database (same OID). | If you have checked the option Overridden Existing Items, the custom field is updated. Otherwise, the update fails and an error is logged accordingly.
Custom field does not exist in the target database. | Import this custom field.
Custom field key exists in the database, related labels do not have the same OID, and OIDs of custom fields are not the same. | Importing this custom field fails, and an error is logged.

To avoid problems that come from missing items, it is recommended that you make importing custom fields the first task among all ACES importing tasks to be run (for example, importing DB Rule and UI Rule required fields, and so on).

Note: Given that no error occurs during exporting and importing of custom fields using ACES, their definitions will be the same on the source and target Service Desk instance once the operation is completed. However, the data mapping model may be different. This means that for the same custom field, a different column name or even a different table could be used in the back-end database. This is because during the import of custom fields, Service Desk automatically creates the table and column in which the custom field's data is stored, and the chosen column and table name depend on database local factors that cannot be controlled by this process.

### Using a custom field in reporting

From the Administrator Console, the administrator has the ability to generate database views in the Service Desk back-end database. These views allow external reporting tools to more easily generate reports on Service Desk. If you use the reporting views and you want to include a newly created custom field a report, you will have to regenerate the reporting views.
The use of the reporting views is described in the section "Generating Database Views" of Chapter 9 of the Service Desk 4.5 Administrator's Guide. For your convenience, the information found there is summarized below.
To (re)generate the reporting views, log in to a Service Desk client as an administrator. Open the Administrator Console, and navigate to System Panel, Report Settings. This opens a window. On the General tab, you will find the option to regenerate the database views.
Please note that to (re)generate the reporting views, you need to enter a time zone. This is because the internal representation of times stored by Service Desk may use a different time zone than the one you are generating the reports for.

## New Custom Fields with Non-Latin Text Support

Whether the new custom fields get non-Latin text support depends not only on the situation in which the custom fields are created but also on the database type of the target database. The new custom fields get non-Latin text support only if all of the following conditions match:

1. It is an Oracle Database, and its Charset is UNICODE (UTF8, AL32UTF8, or UTFE).
2. The option Using Extra Space for Non-Latin Text has been applied to the current database.
3. It is not a long text custom field. (The current String 4K and String 64K are long text fields.)

Note that creating custom fields in this way does not ensure full consistency as does developing custom fields manually. In some special operation scenarios, new custom fields never gain non-Latin text support. For this reason, the administrator should consider this issue before creating new custom fields. An example of such a special situation is shown below:

1. ConFigure a Service Desk database. Do not select the Using Extra Space for Non-Latin Text option.
2. Upgrade the database. Do not select the Using Extra Space for Non-Latin Text option.
3. Create new custom fields.
4. Upgrade the database. Select the Using Extra Space for Non-Latin Text option.

## Generate the Web API

To access newly added custom fields using the Web API, Java developers need to regenerate the Web API, compile it, and replace the original Web API jar file with the new Web API jar file in their Java applications.
To generate the Web API, developers follow these steps:

1. Configure Web API compilation environment.
2. Generate new Web API.
3. Edit build properties and compile the Web API.

### System Requirements and Preparation

#### Install JDK 1.3 or 1.4

To compile the Web API, users need Java™ Development Toolkit (JDK) 1.3 or 1.4 installed on the Service Desk server machine. For instructions, refer to the Service Desk Installation Guide. Suppose you installed JDK1.4 into C:\j2sdk1.4.2_09

#### Install Apache Ant

Download a binary distribution of Apache Ant from `http://ant.apache.org`. At the time of this writing, Ant version 1.6.5, was the most recent version available for download. You should be able to use any version since 1.6.0, however. In the subsequent steps, it is assumed that you extracted the archive with the binary distribution so that its top level directory is called `C:\dev\ant`. If you use a different value, substitute it wherever `C:\dev\ant` is mentioned from this point on.

#### Set Windows Environment Variables (Optional)

Configuring Windows environment variables is an optional task. If users do not change default system environment variables, they must set the variables manually each time before proceeding to the compilation task. The system variables to be configured are `JAVA_HOME`, `ANT_HOME`, and `PATH`. Go to Start -> Preference -> Control Panels -> System, open the System Properties dialog box, navigate to the Advanced tab (See Figure7), double-click Environment Variables, and add the following system variables:

      JAVA_HOME= C:\j2sdk1.4.2_09
      ANT_HOME= C:\dev\ant
      PATH= %JAVA_HOME%\bin;%ANT_HOME%\bin;….

Figure 7

The last ellipse (…) in the "PATH" variable represents the original content of that variable.

After setting environment variables, users can open a command console, and execute the following commands for verification.

      C:\> java –version

      C:\>ant –help
      ant [options] [target [target2 [target3] ...]]
      Options:
       -help, -h print this message
                                      -projecthelp, -p print project help information

Users will see similar output if these environment variables have been set properly.

### Compile the Web API and Javadoc

#### Generate the Web API

To generate the Web API, open the Service Desk client using the system administrator account. From the administrator console, choose File -> Generate Web API. A dialog box for generating the Web API (see Figure 8) appears. Set the Web API destination directory (for example, `C:\Temp\WebAPI`), then click Start Generate. If generation succeeds, users will find all the Web API sources in the destination directory.
Figure 8

#### Configure Build Parameters

Two additional files named `build.xml` and `build.properties`, which are used to build new Web API, are shipped together with this special feature. They reside in the doc\itsm008292 subdirectory of the unpacked Service Pack. Copy them to the Web API destination directory: `C:\Temp\WebAPI`. Open `build.properties`, which contains the following contents:

      # Web API build property file. Hewlett-Packard, Dec 2005

      ###########################################################
      # NOTE: Please change the values of below properties to #
      # match your specified environment. #
      ###########################################################

      # web api sources output directory
      sd_webapi_output_dir=C:/Temp/WebAPI
      # The official web api jar file
      sd_official_webapi=C:/Temp/sp18/api/web-api.jar
      # The official web api javadoc zip file
      sd_official_webapi_javadoc=C:/Temp/sp18/doc/Web API javadoc/web_api_javadoc.zip

Users need to change the values of all the properties defined in this file to match their specific environment. These properties are described in below table.

Property Key | Description
sd_webapi_output_dir | Directory containing the Web API sources.
sd_official_webapi | Qualified file name of official web api jar file.
sd_official_webapi_javadoc | Qualified file name of official Web API javadoc zip file.

In this sample file, the Service Pack is extracted to `C:/Temp/sp18`.

#### Compile the Web API and Javadoc

Open a DOS command console, change the current directory to the Web API destination directory (in this example, `C:\Temp\WebAPI`). Users can configure these system variables manually. If they have not done this (see How to set windows environment), type the following commands to set these variables:

      SET JAVA_HOME=C:\j2sdk1.4.2_09
      SET ANT_HOME=C:\dev\ant
      SET PATH= %JAVA_HOME%\bin;%ANT_HOME%\bin;%PATH%

To show the help text of the Web API build tasks, type `ant help`.

      usage: ANT <target>
      target:
      o [clean ] : delete all files generated when run web api build task
      o [config] : initiate the target properties
      o [build-webapi] : build web api
      o [webapidoc] : build web api javadocs
      o [build-all] : build all the targets
      o [rebuild] : rebuild all targets

      Before building web api, user must configure the properties defined in build.properties. Those properties are:
          sd_webapi_output_dir: Web API source output directory
          sd_official_webapi : The official web api jar file
          sd_official_webapi_javadoc: The official web api javadoc file

      After target [build-all] is successfully run, new web api jar file and web api javadoc file can be found in C:/Temp/WebAPI.

To build Web API jar file and Javadoc, type `Ant`, and press Enter. After the build succeeds, the new Web API jar file will be found in the Web API destination directory. The newly built files are `web-api.jar` and `web_api_javadoc.zip`.

The new `web-api.jar` file can be used on multiple platforms (for example, Windows, HP-UX, or Solaris). Developers should replace the old jar file with the new one to access new custom fields using the Web API in their own web applications.

## Known Errors and Limitations

The unlimited custom fields feature has the following limitations:

1. Please be noticed that the amount of customer fields in your environment could impact the performance.
2. This feature is not intended to be used in a multi-user environment because it modifies the database structure. It is highly recommended that no other client connects to the application server during the import. Also, it is also recommended to have only one application server instance running on the Service Desk database when you define or import new custom fields. Server needs to be restarted after all expected custom fields are created or imported.
3. When creating new custom fields, information like "You have to add a label with oid ... in the language with LCID 1033" will appear in server log. These information can be ignored. During creating new custom fields, two SQL files 'CustomFieldDMLLog.sql' and 'CustomFieldDDLLog.sql' will be generated in Service Desk server installation directory.
4. When a great number of new custom fields are defined for a single item category, the popup menu in Advanced Find for selecting Fields will get too many entries that it no longer fits on the screen. The actual limitation differs according to screen resolution. It also happens with other popup menu for selecting Fields, e.g. rule wizard condition dialog.
5. Custom fields can be created on master items only, which currently include the following:
   - Service Call
   - Problem
   - Incident
   - Change
   - Work Order
   - Project
   - Configuration Item
   - Service
   - Service Level Agreement
   - Maintenance Contract
   - Organization
   - Workgroup
   - Person
6. Any item can have a maximum of 128 long-text custom fields, including the original long-text fields.
7. It is allowed to create new custom fields referring to existing code types but creating new code types is not supported.
8. Using ACES to import new Custom Fields will probably change the data mapping model, please refer to Section Custom Fields Migration with ACES.
9. The new view of Custom Fields (see Figure 1) shows custom fields per item category sorted by validation type. In the dialog to define a new Custom Field, you can select a validation type. In the dialog to edit an existing custom field (which existed before SP18, see Figure 6), the validation type is shown behind the name of the field between parentheses. However, in this dialog (which opens when you double click and existing custom field), the validation types are categorized differently compared to the view of custom fields: many of the new validation types are lumped together under the name of a more generic validation type. Consequently, you could see a different validation type between the brackets of the edit dialog than you see in the tree view. For example, the validation types "number (double)", "number (integer)" and "duration" are all shown as type "number" in the custom field edit dialog, and there are other validation types that are shown as "number" in the edit dialog as well.
   Likewise, custom fields of validation type "Entity reference" will be shown in the custom field edit dialog with the Service Desk item that they refer to between brackets. This is also where the categorization differs between the new custom fields view and the old dialog to edit custom fields.
10. The newly created custom fields can be deactivated if it is no longer used. However, delete function of custom fields will not be supported until future notice.
11. It is possible that the newly generated web-api cannot be compiled. When this happens, you will see an error message similar to "getLbXXXX() is already defined in ..." This problem is caused by unexpected data structures, which can be introduced with database changes made for the implementation of enhancement requests. For example, such changes could cause the database to contain a localized text with a duplicate key, which is something the web-api generation process cannot deal with. To solve the problem, either remove redundant data from the database and generate the web-api again, or remove the duplicate methods from the generated web-api java files. Please refer to ITSM008406 for more information.